<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><link rel="stylesheet" type="text/css" href="style.css" /><script type="text/javascript" src="highlight.js"></script></head><body><pre><span class="hs-pragma">{-# LANGUAGE CPP #-}</span><span class="hs-cpp">
#if __GLASGOW_HASKELL__ &gt;= 701
</span><span class="hs-pragma">{-# LANGUAGE Trustworthy #-}</span><span class="hs-cpp">
#endif
</span><span>
</span><span id="line-6"></span><span class="hs-comment">-- |</span><span>
</span><span id="line-7"></span><span class="hs-comment">-- Module      : Data.ByteString.Short</span><span>
</span><span id="line-8"></span><span class="hs-comment">-- Copyright   : (c) Duncan Coutts 2012-2013</span><span>
</span><span id="line-9"></span><span class="hs-comment">-- License     : BSD-style</span><span>
</span><span id="line-10"></span><span class="hs-comment">--</span><span>
</span><span id="line-11"></span><span class="hs-comment">-- Maintainer  : duncan@community.haskell.org</span><span>
</span><span id="line-12"></span><span class="hs-comment">-- Stability   : stable</span><span>
</span><span id="line-13"></span><span class="hs-comment">-- Portability : ghc only</span><span>
</span><span id="line-14"></span><span class="hs-comment">--</span><span>
</span><span id="line-15"></span><span class="hs-comment">-- A compact representation suitable for storing short byte strings in memory.</span><span>
</span><span id="line-16"></span><span class="hs-comment">--</span><span>
</span><span id="line-17"></span><span class="hs-comment">-- In typical use cases it can be imported alongside &quot;Data.ByteString&quot;, e.g.</span><span>
</span><span id="line-18"></span><span class="hs-comment">--</span><span>
</span><span id="line-19"></span><span class="hs-comment">-- &gt; import qualified Data.ByteString       as B</span><span>
</span><span id="line-20"></span><span class="hs-comment">-- &gt; import qualified Data.ByteString.Short as B</span><span>
</span><span id="line-21"></span><span class="hs-comment">-- &gt;          (ShortByteString, toShort, fromShort)</span><span>
</span><span id="line-22"></span><span class="hs-comment">--</span><span>
</span><span id="line-23"></span><span class="hs-comment">-- Other 'ShortByteString' operations clash with &quot;Data.ByteString&quot; or &quot;Prelude&quot;</span><span>
</span><span id="line-24"></span><span class="hs-comment">-- functions however, so they should be imported @qualified@ with a different</span><span>
</span><span id="line-25"></span><span class="hs-comment">-- alias e.g.</span><span>
</span><span id="line-26"></span><span class="hs-comment">--</span><span>
</span><span id="line-27"></span><span class="hs-comment">-- &gt; import qualified Data.ByteString.Short as B.Short</span><span>
</span><span id="line-28"></span><span class="hs-comment">--</span><span>
</span><span id="line-29"></span><span class="hs-keyword">module</span><span> </span><span class="hs-identifier">Data.ByteString.Short</span><span> </span><span class="hs-special">(</span><span>
</span><span id="line-30"></span><span>
</span><span id="line-31"></span><span>    </span><span class="annot"><span class="hs-comment">-- * The @ShortByteString@ type</span></span><span>
</span><span id="line-32"></span><span>
</span><span id="line-33"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#ShortByteString"><span class="hs-identifier">ShortByteString</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-34"></span><span>
</span><span id="line-35"></span><span>    </span><span class="annot"><span class="hs-comment">-- ** Memory overhead</span></span><span>
</span><span id="line-36"></span><span>    </span><span class="hs-comment">-- | With GHC, the memory overheads are as follows, expressed in words and</span><span>
</span><span id="line-37"></span><span>    </span><span class="hs-comment">-- in bytes (words are 4 and 8 bytes on 32 or 64bit machines respectively).</span><span>
</span><span id="line-38"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-39"></span><span>    </span><span class="hs-comment">-- * 'B.ByteString' unshared: 9 words; 36 or 72 bytes.</span><span>
</span><span id="line-40"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-41"></span><span>    </span><span class="hs-comment">-- * 'B.ByteString' shared substring: 5 words; 20 or 40 bytes.</span><span>
</span><span id="line-42"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-43"></span><span>    </span><span class="hs-comment">-- * 'ShortByteString': 4 words; 16 or 32 bytes.</span><span>
</span><span id="line-44"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-45"></span><span>    </span><span class="hs-comment">-- For the string data itself, both 'ShortByteString' and 'B.ByteString' use</span><span>
</span><span id="line-46"></span><span>    </span><span class="hs-comment">-- one byte per element, rounded up to the nearest word. For example,</span><span>
</span><span id="line-47"></span><span>    </span><span class="hs-comment">-- including the overheads, a length 10 'ShortByteString' would take</span><span>
</span><span id="line-48"></span><span>    </span><span class="hs-comment">-- @16 + 12 = 28@ bytes on a 32bit platform and @32 + 16 = 48@ bytes on a</span><span>
</span><span id="line-49"></span><span>    </span><span class="hs-comment">-- 64bit platform.</span><span>
</span><span id="line-50"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-51"></span><span>    </span><span class="hs-comment">-- These overheads can all be reduced by 1 word (4 or 8 bytes) when the</span><span>
</span><span id="line-52"></span><span>    </span><span class="hs-comment">-- 'ShortByteString' or 'B.ByteString' is unpacked into another constructor.</span><span>
</span><span id="line-53"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-54"></span><span>    </span><span class="hs-comment">-- For example:</span><span>
</span><span id="line-55"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-56"></span><span>    </span><span class="hs-comment">-- &gt; data ThingId = ThingId {-# UNPACK #-} !Int</span><span>
</span><span id="line-57"></span><span>    </span><span class="hs-comment">-- &gt;                        {-# UNPACK #-} !ShortByteString</span><span>
</span><span id="line-58"></span><span>    </span><span class="hs-comment">--</span><span>
</span><span id="line-59"></span><span>    </span><span class="hs-comment">-- This will take @1 + 1 + 3@ words (the @ThingId@ constructor +</span><span>
</span><span id="line-60"></span><span>    </span><span class="hs-comment">-- unpacked @Int@ + unpacked @ShortByteString@), plus the words for the</span><span>
</span><span id="line-61"></span><span>    </span><span class="hs-comment">-- string data.</span><span>
</span><span id="line-62"></span><span>
</span><span id="line-63"></span><span>    </span><span class="annot"><span class="hs-comment">-- ** Heap fragmentation</span></span><span>
</span><span id="line-64"></span><span>    </span><span class="hs-comment">-- | With GHC, the 'B.ByteString' representation uses /pinned/ memory,</span><span>
</span><span id="line-65"></span><span>    </span><span class="hs-comment">-- meaning it cannot be moved by the GC. This is usually the right thing to</span><span>
</span><span id="line-66"></span><span>    </span><span class="hs-comment">-- do for larger strings, but for small strings using pinned memory can</span><span>
</span><span id="line-67"></span><span>    </span><span class="hs-comment">-- lead to heap fragmentation which wastes space. The 'ShortByteString'</span><span>
</span><span id="line-68"></span><span>    </span><span class="hs-comment">-- type (and the @Text@ type from the @text@ package) use /unpinned/ memory</span><span>
</span><span id="line-69"></span><span>    </span><span class="hs-comment">-- so they do not contribute to heap fragmentation. In addition, with GHC,</span><span>
</span><span id="line-70"></span><span>    </span><span class="hs-comment">-- small unpinned strings are allocated in the same way as normal heap</span><span>
</span><span id="line-71"></span><span>    </span><span class="hs-comment">-- allocations, rather than in a separate pinned area.</span><span>
</span><span id="line-72"></span><span>
</span><span id="line-73"></span><span>    </span><span class="annot"><span class="hs-comment">-- * Conversions</span></span><span>
</span><span id="line-74"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#toShort"><span class="hs-identifier">toShort</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-75"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#fromShort"><span class="hs-identifier">fromShort</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-76"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#pack"><span class="hs-identifier">pack</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-77"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#unpack"><span class="hs-identifier">unpack</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-78"></span><span>
</span><span id="line-79"></span><span>    </span><span class="annot"><span class="hs-comment">-- * Other operations</span></span><span>
</span><span id="line-80"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#empty"><span class="hs-identifier">empty</span></a></span><span class="hs-special">,</span><span> </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#null"><span class="hs-identifier">null</span></a></span><span class="hs-special">,</span><span> </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#length"><span class="hs-identifier">length</span></a></span><span class="hs-special">,</span><span> </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#index"><span class="hs-identifier">index</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-81"></span><span>
</span><span id="line-82"></span><span>    </span><span class="annot"><span class="hs-comment">-- * Low level conversions</span></span><span>
</span><span id="line-83"></span><span>    </span><span class="annot"><span class="hs-comment">-- ** Packing 'Foreign.C.String.CString's and pointers</span></span><span>
</span><span id="line-84"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#packCString"><span class="hs-identifier">packCString</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-85"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#packCStringLen"><span class="hs-identifier">packCStringLen</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-86"></span><span>
</span><span id="line-87"></span><span>    </span><span class="annot"><span class="hs-comment">-- ** Using ByteStrings as 'Foreign.C.String.CString's</span></span><span>
</span><span id="line-88"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#useAsCString"><span class="hs-identifier">useAsCString</span></a></span><span class="hs-special">,</span><span>
</span><span id="line-89"></span><span>    </span><span class="annot"><a href="Data.ByteString.Short.Internal.html#useAsCStringLen"><span class="hs-identifier">useAsCStringLen</span></a></span><span>
</span><span id="line-90"></span><span>  </span><span class="hs-special">)</span><span> </span><span class="hs-keyword">where</span><span>
</span><span id="line-91"></span><span>
</span><span id="line-92"></span><span class="hs-keyword">import</span><span> </span><span class="annot"><a href="Data.ByteString.Short.Internal.html"><span class="hs-identifier">Data.ByteString.Short.Internal</span></a></span><span>
</span><span id="line-93"></span><span class="hs-keyword">import</span><span> </span><span class="annot"><a href="../../base/src/Prelude.html#"><span class="hs-identifier">Prelude</span></a></span><span> </span><span class="hs-special">(</span><span class="hs-special">)</span><span>
</span><span id="line-94"></span><span>
</span><span id="line-95"></span></pre></body></html>